Hyper Stacks 1994 May

home *** CD-ROM | disk | FTP | other *** search

/ Hyper Stacks 1994 May / Hyper Stacks (Pacific HiTech)(1994)[Mac].iso / Utilities / HC 21 Tech Notes < prev next >

Wrap

Internet Message Format | 1991-09-25 | 23.9 KB | [TEXT/MSWD]

From: strick@slcs.slb.com Date: Fri, 28 Jun 91 11:39:57 CDT Subject: HyperCard 2.1 Release Notes (AppleEvents) > ... I see 'File Sharing Extension' and 'Finder' as two programs > apparently supporting events. Where can I get docs on sending > them events? I don't know about File Sharing Extension. I do know about the Finder -- the suite of Apple events that the 7.0 Finder understands will be published in the Apple Event Registry, a version of which will shortly be available from the Apple Programmers' and Developers' Association (APDA). However, you'll need an XCMD to send these events to the Finder from HyperCard 2.1. > Can you give me a HyperTalk string that will send an event to the > Finder on another (7.0 w/linking) Mac that will tell it to launch > HyperCard? If I can get HC running then I can use it to launch > other Apps and such, but I'm guessing I should be able to tell the > finder to oapp HyperCard? Unfortunately, the Finder does not accept standard open events from remote machines -- I believe that this decision was made by the 7.0 team to make the whole program linking scheme more secure from viruses. Therefore there is no way at present to launch an app on a remote machine from HyperCard, unless HyperCard or some other app that can sublaunch things is running on that machine. I can only recommend two things: - Put HyperCard in the Startup Items folder in the System Folder. This will make it launch automatically when the machine boots. - Find or write a nice small utility app that can accept some of the standard Apple events from remote machines and put it in the Startup Items folder. Here, as promised, are the articles I posted to comp.sys.mac.hypercard. ----- HyperCard 2.1 Release Notes Overview of this Release ------------------------ HyperCard 2.1 is the version of HyperCard recommended for use with System 7.0. It is also compatible with System 6.0.5 and System 6.0.7. Revisions for Support of System 7.0 Features -------------------------------------------- These revisions are grouped by their associated Toolbox Manager. Alias Manager When the Alias Manager is present, HyperCard 2.1 will call it to resolve alias files. Therefore, the following commands will work properly with alias files. go to stack <alias file> open <alias file> with <alias file> open file <alias file> write to file <alias file> read from file <alias file> picture <alias file> The XCMD callback GetFilePath will also resolve alias files. Therefore, XCMDs that use this callback to locate files will require no revision to work with alias files. (The Picture XCMD is an example.) In addition, if HyperCard finds an alias file when looking for the Home stack on startup, the alias file will be resolved. Apple Event Manager When the AppleEvent Manager is present, HyperCard 2.1 will use it to process and send Apple events. HyperCard will recognize and handle the standard Apple events for opening documents, printing documents, quitting, executing a script, and evaluating an expression. In addition, several of HyperTalk's built-in commands will have the added ability to send specific Apple events to other applications. Event class Event ID Related HyperTalk command ----------- -------- ------------------------- 'aevt' 'oapp' open <application> 'aevt' 'odoc' open <document> with <application> 'aevt' 'pdoc' print <document> with <application> 'aevt' 'quit' close <application> 'aevt' 'clos' close <document> with <application> 'misc' 'dosc' send <expr> to program <programExpr> 'misc' 'eval' request <expr> of program <programExpr> If you want to launch another application or open a document with another application, use the HyperTalk command "open". If you want to print a document with another application, use the command "print". If you want to close a document in another application or quit another application, use the command "close". If you want to execute a script or macro in another application, use the HyperTalk command "send". If you want to evaluate an expression in another application, use the command "request". Please note that among these Apple events, only 'oapp', 'odoc', 'pdoc', and 'quit' are universally supported. All other Apple events that HyperCard can send will be effective only if the target application includes specific support for them. For example, close "My Expense Report" with "FabCalc" will work properly only if the application FabCalc supports the 'clos' Apple event. The "open", "print", and "close" commands will work only with applications that reside on the same machine as HyperCard. The "send" and "request" commands will work with any linkable program running on the network. See "Determining the Target Program", below. Sending scripts to other programs The send command in HyperTalk will send a "do script" Apple event from HyperCard to another application running remotely. It can be used to send a script to any program that understands the standard 'dosc' Apple event. By default, HyperCard waits for a reply from the target program before continuing. However, you can specify that you don't want to wait for a reply. Examples: send "make waves" to program "De Anza 6/2nd:WildCraft:HyperCard" send "build {project}" to program "MPW Shell" without reply Evaluating expressions in other programs The request command in HyperTalk will send an "evaluate expression" Apple event from HyperCard to another application running remotely. It can be used to send an expression to any program that understands the standard 'eval' Apple event. The value of the expression will be put into the local variable "it". Examples: request "the name of this stack" of program "HyperCard" request "{target}" from program "MPW Shell" Handling failures The "send", "open", "print", "close", and "request" commands set "the result" as follows when they fail. Condition the result --------- --------------- User canceled the "Link to program" "Cancel" dialog. Target program didn't handle event. "Not handled by target program" Target program timed out. "Timeout" Target program returned error string the string in reply. Target program returned error number "Got error <errorNum> in reply, or AESend returned some when sending Apple( event" other error. Establishing program links When sending Apple events to another program, if HyperCard has not established a link with the target program, the user will be presented with a dialog, through which the link will be established. If a link has already been established between HyperCard and the target program, the Apple event will be sent without further user interaction. Determining the target program The target program for Apple events is specified by a string in the following format: zone:machine:program Examples: "Fifth Floor:Gizmo:MacWrite" "Baby mac:MacWrite" -- zone omitted; HyperCard assumes same zone MacWrite -- zone and machine omitted; HyperCard assumes same zone, same machine HyperCard's address on the network is contained in the property, "the address". You can use the itemDelimiter property to parse program addresses. For example, given a string that specifies a target program, the following HyperTalk function will return the name of the program if you send it a colon as the delimiter and the string as the text. function lastHCItem delim,theText put the itemDelimiter into savedDelimiter set the itemDelimiter to delim put the last item of theText into lastItem set the itemDelimiter to savedDelimiter return lastItem end lastHCItem Choosing a target program The answer command has been extended for use with the Program Linking dialog, so that scripters can allow users to select a program to link to. answer program prompt { of type <factorList> } When used in this way, the answer command displays the PPC browser, from which the user can select any program running on any machine connected to the AppleTalk network. A string representing the program the user selects is placed into the local variable "it". Examples: answer program "Where did you say that program was again?" answer program "Choose a spelling checker:" of type "Spellcheck" In addition, a scripter can determine which programs are running on the same machine as HyperCard by examining the new HyperTalk function, "the programs". It returns a return-delimited list of all the linkable programs currently running on the same machine as HyperCard. Handling Apple events When HyperCard receives an Apple event, it will send a new HyperTalk system message, "appleEvent", to the current card, along with parameters that enable a script to determine the class, id, and the sender of the Apple event. For example, when the Finder sends HyperCard an Apple event of class 'aevt' and id 'odoc', HyperCard sends the HyperTalk message "appleEvent aevt,odoc,Finder" to the current card. A script that handles an appleEvent message can gather the parameters of the Apple event by using the new HyperTalk command "request". request appleEvent data { [ of | with ] keyword <expr> } This command puts the parameter or attribute with the specified keyword into the local variable "it". For example, you can obtain a parameter of keyword "errs", the standard Apple event keyword for an error string, as follows: request appleEvent data with keyword "errs" put it into errorString If there is no attribute or parameter with the keyword you specify, HyperCard sets the result to "Not found". If you don't supply a keyword, HyperCard assumes you're requesting the direct object of the Apple event, which is defined by the Apple event manager as the parameter with keyword "----". The request command also supports several special cases for important attributes of Apple events: request appleEvent class request appleEvent id request appleEvent sender request appleEvent return id HyperCard will attempt to convert all the Apple event parameters to strings, for use in HyperTalk. The Apple event manager automatically handles the conversion of numerical forms to strings; HyperCard installs coercion handlers for alias records, return ids, process serial numbers, target ids, class and id types, and lists. If an incoming Apple event specifies that user action is not permissible, the global property lockErrorDialogs will automatically be set to TRUE (see "Error Handling", below). The scripter can override this setting. Example: a scripter defines an event of class 'WILD' and id 'cnvt' as a request to convert a 1.2.5 stack to the 2.0 file format. The direct object of the Apple event is defined to be the pathname of the stack. The following script will do the trick. on appleEvent eventClass,eventID,sender if eventClass & eventID is not "WILDcnvt" then pass appleEvent else request appleEvent data if it is empty then exit appleEvent go to stack it if the result is not empty then exit appleEvent if there is a menuItem "Convert Stack..." in menu "File" then doMenu "Convert Stack..." without dialog end if end appleEvent Example: when a stack is opened from the Finder while HyperCard is running, HyperCard 2.1 will open the stack in a new window. This behavior is different from previous versions of HyperCard, which would go to the stack in the currently active window. If you prefer the old behavior, you can put the following script in your Home stack. on appleEvent eventClass,eventID,sender if eventClass & eventID is not "aevtodoc" then pass appleEvent else request appleEvent data put line 1 of it into stackToOpen go to stack stackToOpen end if end appleEvent If HyperCard receives the appleEvent message, either because it was not intercepted by a script or because it was passed to it by a script, HyperCard will check whether the current Apple event is of the types it knows how to respond to, and if so, will treat it appropriately. HyperCard 2.1 will recognize the following standard Apple events: 'odoc', 'pdoc', 'quit', 'dosc', and 'eval'. HyperCard responds to the 'odoc' event by checking whether the specified files are stacks and, if so, opening them, each in a new window. HyperCard responds to the 'pdoc' event by checking whether the specified files are stacks and, if so, opening them one at a time in a new window, printing them, and closing them again. HyperCard responds to the 'quit' event just as it would if "Quit HyperCard" were chosen from the File menu. HyperCard responds to a 'dosc' event by compiling and executing the HyperTalk statements sent to it as the direct object of the event. HyperCard responds to an 'eval' event by evaluating the expression sent to it as the direct object of the event and putting the value into the direct object of the reply. Replying to Apple events Scripters can reply to Apple events from HyperTalk with a new command, "reply". reply <expr> { with keyword <expr> } If you don't specify a keyword for the reply parameter, the parameter will become the direct parameter of the reply. If you wish to return an error string, you can use the following form of the reply command: reply error <expr> This is equivalent to: reply <expr> with keyword "errs" The reply event is sent when the chain of execution is complete. For example, the following script will handle Apple events of class 'WILD' and type 'defn' by searching for a string in a background field named "Glossary Entry" and returning the contents of a background field named "Definition". on appleEvent eventClass,eventID,sender if eventClass is "WILD" and eventID is "defn" then request appleEvent data find it in field "Glossary Entry" if the result is empty -- successful find then reply field "Definition" else reply error "Not found" else pass appleEvent end appleEvent The "request" and "reply" commands set the result to "No current Apple( event." when there is no current Apple event to handle. Miscellaneous Revisions ----------------------- Menus When you ask for the names of the Apple, Help, and Application menus >From HyperTalk, you get "Apple", "System Help", and "Application", respectively. Error Handling In order to execute scripts without interaction with the user, as well as to provide a better means for testing HyperCard's error messages, it's now possible to lock error dialogs and to put HyperTalk into a "quiet mode" for script execution. When HyperTalk encounters an error while in "quiet mode", it aborts execution of pending scripts just as it normally would, but instead of displaying a dialog with an error message, it sends a "errorDialog" message to the current card with the error message as its parameter. This message substitutes for the first "idle" message that would be sent in normal mode after HyperTalk cleans up and HyperCard returns to its main event loop. Example: set lockErrorDialogs to TRUE -- puts HyperTalk into "quiet mode" lock error dialogs -- an alternate form unlock error dialogs When HyperCard receives an Apple event for which the sender has specified that no user interaction is allowed, it will automatically set lockErrorDialogs to TRUE before handling the event. Determining which version of System Software is running A new function has been added to HyperTalk, "the systemVersion". It returns the version of system software is running in a decimal string. For example, it will return 6.07 instead of 6.0.7, to allow scripters to use it with HyperTalk's arithmetic operators. Specifying Windows You can now refer to windows by number and by id as well as by name. Therefore, the following commands are now valid. get the id of the card window set the loc of window 1 to 50,50 hide last window Both the Picture and Palette XCMDs now send the id of a newly created window as an additional parameter to its open message. For example, after the Picture XCMD creates a new window, it sends the following message to the current card: openPicture <name of window>,<id of window> Read and Write The HyperTalk "read" and "write" commands have been enhanced. The following examples are now valid. read from file "Fred" at 100 for 12 read from file "Fred" until end -- 'eof' works too write myVar to file "Fred" at 200 write moreStuff to file "Fred" at end -- 'eof' works too In addition, the 16K limit on the amount of text that could be read at once has been removed. If the amount of text you ask for won't fit in memory, HyperCard sets the result to "Not enough memory to read from file." Getting the internal modem for the Portable to work with "dial" A new global property, "the dialingTime", has been added, especially for users of the internal modem for the Macintosh Portable. It determines how long HyperCard waits, in ticks, after sending the dial string, before closing the serial connection with the modem. The default is 180 (3 seconds). Owners Windows and cards now have an "owner" property. For windows, the owner is determined as follows. Creator Owner ---------- ---------- HyperCard "HyperCard" desk accessory or driver "System" XCMD the name of the XCMD anything else "Unknown" The owner of a card is the name of its background. More Parameters Available The parameters for the "start", "stop", and "set" commands are now available within overriding handlers. Summary ------- New messages: appleEvent, errorDialog New commands: request, reply New functions: programs(), systemVersion() New properties: the address, the itemDelimiter, the lockErrorDialogs, the dialingTime, the owner New constants: comma, colon Enhanced commands: open, print, close, send, read, write, answer, lock, unlock, set, start, stop ----- When HyperCard 2.1 receives an Apple event, it sends an appleEvent message to the current card. That means that you can respond to Apple events with HyperTalk scripts. But before you try to write such scripts, there are some terms and conventions you should be familiar with. The figure ---------- Apple events are like a package full of raw materials that arrive at a factory. They have a return address on them -- in HyperTalk, a string of the form "Zone:Macintosh:Program". They have an explanation of what their contents are for -- the class and id, which together consititute a verb, directing the receiver what do to with the package. And of course there are the contents themselves -- the event parameters. When you get one of these packages, you have to unpack it before you can make something out of the raw materials inside. But you can't just rip into the package willy-nilly. You have to ask for what you want, by name. "Give me the snod." "OK, now give me the lerd." You unpack the contents, one by one, and make out of them whatever you're directed to make by the class and id. The catch is that the package doesn't come with a packing list. You're supposed to know what's in it -- you have a big book that tells you that whenever you get a package that you're supposed to make into a "wild plum", it's supposed to have a "bork", a "flam", and a "nitz" inside of it. So you unpack the bork, the flam, and the nitz, and then you make the wild plum out of them and send it back. Apple event = package class and id = terse directions for what to do with the package parameters = contents of the package keywords = names for each thing in the package The lesson ---------- In HyperTalk, when you handle the appleEvent message, you first look at the class and id, and they tell you what you're supposed to do with the event. If it's an event that you know how to handle, you already know what the parameters are -- you've agreed with the sender in advance on what's supposed to be in it, or it's a standard Apple event defined in the voluminous standard documentation. So you unpack the parameters with the "request" command, manipulate them, and send back what you made out of them with the "reply" command. The script might look like this: on appleEvent class,id,sender if class & id is "wildplum" then request ae data with keyword "bork" if the result is not empty then -- probably "Not found" reply error "Expected a bork but got none." exit appleEvent end if put it into theBork request ae data with keyword "flam" . . . . get wildPlumMakingFunction(theBork,theFlam,theNitz) -- process it reply it -- send back the reply else pass appleEvent -- we don't recognize this event; pass it on end appleEvent Keywords -------- Think of a keyword for a piece of data in the package as its name -- it's the handle you need to pull it out of the package. Asking for a parameter by keyword is the same as asking for a piece of raw material by name. Keywords are arbitrary. Whoever invents an Apple event makes them up, on the spot, out of the blue, to name the pieces of data that go along with the event. The standard Apple events that have already been defined, along with the keywords for their required and optional parameters, are described in the Apple Event Registry. The direct object ----------------- Many Apple events arrive with just one piece of raw material in them, or one piece that's more important than the others. By convention, this piece is given the keyword "----" and is referred to in the Apple event documenation as "the direct object" or "the direct parameter". These are pretty ugly names, so in HyperTalk you can just call it the "data" and leave off the keyword specification -- HyperCard will know what you're talking about. request appleEvent data This is equivalent to the following statement. request appleEvent data of keyword "----" The direct object for the 'odoc' event is the list of documents to open. The direct object for the 'dosc' event is the script to execute. And so on. Event attributes ---------------- Apple events come along with more than just an address, a verb, and pieces of data. They also come with modifiers, or "attributes", which you can think of as "special handling instructions". The class, id, and sender are all attributes also, but HyperCard gives you these automatically as parameters to the appleEvent message. The timeout value, the transaction id, and the return id -- the identifier you put on the reply so that the sender knows, when his wild plum arrives, which package you made it out of -- are additional attributes. If you need to look at these, the "request" command will let you. You can get the return id, request appleEvent return id request appleEvent data of keyword "rtid" -- same thing, only uglier the timeout value, request appleEvent data of keyword "timo" the transaction id, request appleEvent data of keyword "tran" and whatever else you think you need, as long as you know its keyword. We have special forms of the request command for the class, id, sender, direct object, and return id -- for everything else, you have to tell HyperCard what you want by keyword. request appleEvent class -- gives you the class attribute request appleEvent id -- gives you the id attribute request appleEvent sender -- gives you the sender attribute request appleEvent data -- gives you the direct object parameter request appleEvent return id -- gives you the return id attribute